ZX FTP client, ver. 1.0- instructions
*************************************

FOREWORD
********

Dear Wifi users, with big happinnes and proudness in my heart, I present to the ZX world one of the first FTP clients for ZX Spectrum. It took me 13 months of ceaseless work so far. The result is quite satisfying. It is probably the most useful program I have written for ZX Spectrum so far.

Previous version 0.7 was not able to display and browse directory content. Version 1.0 can do it.

I designed version 1.0 in a way, so that it can be ported to another hw configuration most easily. In version 1.0, I may only fix bugs or add something minor but do not plan to extend it anymore. Instead, I plan next versions specially bound to eLeMeNt ZX and MB03+ Ultimate (www.128land.com) hardware to make the client better. So if you are interested in porting version 1.0 to another ZX system, version 1.0 is practically the best (and only) starting point. In that case, just ask me for details.

Version 1.0 is able to run on ZXS 48K. It has only tens of bytes free space, but I want to keep it for bug fixing.

The main code of the client uses latest Wifi Bios ver 1.8. and Speed Management 2.0. The bios ensures low level routines and Bios as well as Speed Management 2.0 can be used independently in other applications too. Both make it easier for wifi coder to code their programs.

The source code consinst of extra sources: binary font, keyboard and print source, keyboard read routine by Busy and disk opeartion source for easier porting to another disk systems.

If porting, keep in mind, that the wifi device we use is placed in MB03+, it is ESP-01 module, the same one as was used in first batch of ZX Next. Writing your own wifi bios for your wifi hw would be the easiest option to port the client to hw of your favour.


REQUIREMENTS
************
- MB03+ interface fitted with Wifi module ESP-01
- BSDOS disk operating system


MAIN FEATURES
*************
Version 1.0 is ideal for downloading and uploading ZX programms between FTP server and your ZX computer, without need of removing your memory card. It also enables you to organise directories and files on the server.


FEATURES
********
- it can connect to local, remote as well as mobile ftp servers
- it useses 20 ftp commands (previous release 0.7 had 10)
- it uses command prompt for you to write other commands directly to the server
- display and browse directory
- mark files
- find files
- upload one file
- download multiple files
- create directory
- rename files/ directories
- delete files/ empty directories
- maximum items that the directory is able to hold up is roughly 500- 1200 items



ZX MEMORY
*********
Version 1.0 executive code starts from #C800 (51200). It also uses buffer memory from #6000 to #C7FF. It is used for upload and download files and for directory. Since this memory is shared, directory has to be reread each time after file has been up/downloaded. Executive memory could be extended, but only at a cost of diminshing buffer memory, which would result in less place for directory items. Stack pointer starts at #6000 and goes down. For multiple item operations, memory from #4800- #4FFF is in use too.


CONTROL KEYS
************
Control keys can be divided into 2 groups. First is controls 1) without directory read, second 2) controls for directory operation.

1)- general control keys
- F- file: 	allows user to enter their default file name which will be downloaded always when pressing SS+D
- T- start:	allows user to enter their default start address for files being downloaded
- A- autologin:	select if automatic login should be carried out upon client start
- H- host:	select your ftp server URL
- E- usr:	enter ftp server user
- P- pass:	enter ftp server password
- SS+P:		show/hide displayed password
- U- upl:	upload file, enter its name
- S- size:	returns item size, enter its name
- Q- quit:	quit client (ftp connection remains)
- W- wifi:	on/off. Sets your wifi state upon client quit
- L- login	login to ftp server, user and password will be entered manually
- SS+L		login to ftp server, user and password are taken from variables
- O- logoff	logg of ftp server
- V- savApp	save application with its settings and variables
- D- dwnld	download file/s
- ss+D		download file, name and start address taken form variables
- CS+D		download file, name entered manually
- C- com	enter ftp command

2)- directory control keys
- I- Fn		find item
- Spc		space- un/mark item
- Z,X		roll directory item if it is longer than screen
- R- Rr		reread directory
- 6- Rn		rename item
- 7- MD		make new directory
- Del		delete item/s
- Br- UD	break key, jump up directory
- N		change way of directory retrieve (NLST/ LIST)
- ss+N		read directory abbreviated or full
- Enter		enter directory
- arrows	up/down for browse directory up/down or left/ right for page up/down

In the course of your work, where available, use B key to abort action.


SCREEN ORGANISATION
*******************
The screen can be divided into 3 parts. Upper, middle and lower.

Upper part.
- line 1,2	Author+ version number, or directory path.
- line 3	Speed: speed info (default is 16, which is max), speed cannot be changed
		Logged in: OK for being logged in, X the opposite
		STATUS: 2- module connected to AP and IP is obtained
			3- TCP transmission created (this is the state you want)
			4- TC transmission disconnected
			5- module is not connected to AP (Acess Point) at all
- line 4	Host: shows URL of your ftp server, or X if not connected
- line 5,6,7	answers from FTP server

Middle part
- line 8-15	FTP directory

Lowe part
- line 16	related to FTP directory.
			showing number of items/ directories/ files
			directory control keys
- line 17:	File: variable file name, that the user can change.
		Start: variable start address for downloaded file, that the user can change
- line 18:	Host: variable host name, that the user can change
		User: user name for login, that the user can change
		Pass: password for login, that the user can change
- line 19,20:	general control keys
- line 21:	number of marked files
		directory retrieve mode (LIST/NLST/full/abbr)
- line 23:	info line guiding the user throughout their action
- line 24:	input line


INPUT LINE FEATURES
*******************
Throughout your work input prompt line apperas on the screen. The input line uses these keys:
- left/right- for moving your cursor
- TRUE VIDEO- for input abort
- DELETE
- GRAPH- for backspace
- SS+Q- for jump on line start


SETUP
*****
There is no setup or configuration file for the moment. ZX FTP client works as a single file. The reason is, that on BS-DOS you will be able to run it from a remote path (using eg. NEW#3,25 command, meaning "run file number 25 from disk 3). More info how to handle setup, see below.


LOGGING IN
**********
The client has quite convenient way of logging in to ftp server. First of all, the client contains host url, user and password variables, which the user can change. At the same time, you can set auto login variable with A key. If set to yes, the client performs automatic login to ftp server. If set to no, it does not.


SERVERS
*******
Communicating with server is probably the trickiest part of the whole client. Different server types and setting or restrictions can make it impossible or hard to access such servers. The client should be able to access any ftp server in the world, including mobile phone ftp servers, which do not operate on port 21 (standart ftp port), but on a different ports. ON ZX Spectrum, we are quite dependent on the server as 8 bit ZXS does not have enough power to organise obtained data much. Theoretically, any ftp server can behave in a different way. If you run upon the server, of which data the client processes badly, let me know.

In case your server is a standart one (ie. it uses standart FTP port 21), just enter it with key H in normal way. Like "192.168.0.200", or "hood.speccy.cz". If your server uses different port (eg. 31546), enter its URL like this: "192.168.0.200:31546", or "hood.speccy.cz:31546".


DIRECTORY
*********
I think, work with directory should be the essence of the FTP client. Although we are quite limited with ZXS possibilities how to process incoming directory data. Out of the few servers I tried, all of them returned directory items (be it directory or file) in alphabetical order, which is a nice feature for the user. I found no way, how the client could make the server send data how the client dictates. Almost all servers I tested did not distinguish between directory and file. All were just items. It means, directories starting with eg. Z letter were sent at the end of directory list. The only one exception were mobile phone servers, some of them returned directories first, and then files- all in alphabetical order, which, I believe, is an ideal. Organising items in different way would require very sophisticated routines on ZX side, more memory and long waiting time. I think, we can forget about it for the moment.


WORKING WITH DIRECTORY
**********************
Directory is closesly bound with memory. The free memory for directory is #6800 bytes (26624 in decimal). It often happens this is not enough even for ZX files to hold them all. If the memory has run out during directory retrieve, the client will show a message "Transfer incomplete". Then there is an information about number of directories or files or items stored in your memory displayed just a line below directory itself.

Retrieving directory can be done in 3 modes (see ss/+N control):
1) LIST full
LIST is an ftp command that returns complete items (like: attributes, owner, date, time, length, etc.).  This mode brings you all the data. Use this mode only in case other modes fail you, it shows you the way the server returns the directory. In this mode the client cannot work, since the data can varry a great deal. Some example could look like this:
-rw-r--r-- 1 ftp ftp          27582 Feb 03  2022 03.lim
-rw-r--r-- 1 ftp ftp          30913 Feb 03  2022 03.scr
drw-r--r-- 1 ftp ftp          22445 Feb 03  2022 04
-rw-r--r-- 1 ftp ftp          30913 Feb 03  2022 04.scr

2) LIST abbr
same as mode 1, but this time redundant data will be removed, meaning ZX memory can hold more items. Directories start always with "D" at the line start. This is the default mode and could look like this:
       27582 Feb 03  2022 03.lim
       30913 Feb 03  2022 03.scr
D      22445 Feb 03  2022 04
       30913 Feb 03  2022 04.scr

3) NLST full
NLST is an ftp command and it returns item names only. For us this is the most economical way of storing items. This mode is always reliable, but you cannot differ between a directory and a file, that's why I reffer to them as items. However, entering an item that may look like dir, the client will try and if it is directory, it should not fail. The output looks like this:
03.lim
03.scr
04
04.scr

It can happen, one directory entry is longer than the whole screen. You recognise such an entry by two ending dots. In this case, press "X" and "Z" to roll through the item to see it complete.


DELETING DIRECTORY
******************
If the directory is empty, there is no issue deleting it. If not empty, FTP refuses to do it. The directory have to be entered, all items marked and deleted. However, in version 1.0 you have to do it manually. There is a lack of memory for such action.


JUMPING FROM DIRECTORY
**********************
You can either move the cursor to the very first item in the directory ".." and press enter, or more convenient, press break key at any time, it does the same.


MARKING ITEMS
*************
With the space key, you can mark or unmark files. Other ways of marking files is with find function, see below. Un/mark all is not supported in version 1.0.


FIND
****
This is very useful function, lifting the client a level higher at only several bytes cost. You may enter any kind of string, the client will look up the item name for you in the directory. Matching items are highlithed in red and their number will be displayed on the third bottom line. At the same time you will be transfered to the first matching item. Find function is case insensitive. If you enter just one letter, all items starting with this letter will be found- this is very useful, if you just need to move to certain letter in the list. Found items will become marked items.

Let's say you want to find all tap files. Simply enter ".tap" and all matching files will be highlighted for you.  


UPLOAD
******
In version 1.0 as opposed to the previous 0.7 I added STOU command upon which the server creates a new file in case the name already exists. Press U, enter file name from your disk and upload will start. Speed is around 3 kb/ sec.


DOWNLOAD
********
There are 3 was of how to download file.

SS+D= download file from file name variable and assign it with start address from the variable. This is very handy when you eg. need to test one file (eg. you are writing an executive code on PC) and want to download it all the time.

CS+D= enter file name you want to download manually.

D= download file under cursor. If there are marked files, than the one under your cursor will be ignored and all marked files will be downloaded.

Download speed using 20 Mhz CPU should be around 60 kb/sec.


DIRECT COMMAND INPUT
********************
True, that version 1.0 can operate 20 ftp command. While there are others, that are not implemented. I avoided their implemenattion in order to spare memory. Instead, you can type them using C controll, case insensitive. Thus, you may enter eg. command SITE, upon which the server returns you all FTP commands supported by the server. Commands which need 2 channel work (communication and data channel, like LIST, RETR...), will not work in this mode. They work in the main program instead.


LOCAL FTP SERVER
****************
It is advisible to install your local server to be able to copy files from your ZX to PC and vice versa. In the package you will find FileZilla server and its interface which I find both, small and easy to install and set. Since there is no directory listing in ver 0.7. you have to know file names, and the easiest way is to have your PC screen with files open (together with the running client on ZX), and read file names you want to work with. In the server interface, you need to add a new user and password, assign a path to your drive on PC that the client will work with and enable work with files (delete, append, etc.) see the picture below. I found the latest versions incovenient to set, so I use this old version instead. But practically, you can use any local ftp server of your wish.


IDDLE TIME
**********
The client sends a NOOP command roughly every 1 minute to keep your connection alive and to prevent being kicked off by the server for inactivity. However, some servers can monitor traffic and kick you off, despite NOOP command sending.


ERROR CODES
***********
Serve mainly for my purposes, but you may encounter them, here is the list for you:

	;1=sending string error (cipsend_request routine)			...OK
	;2=error sending CWMODE AT commad					...OK
	;3=error sending CIPMUX AT command					...OK
	;7=error sending CIPCLOSE AT command (ftp upload)			...OK

	;8= module did not return SEND OK after data block sending (ftp_upl_send)..OK
	;9= error in entering passive mode (enter_passive_mode)			...OK
	;14=file not exist							...OK
	;15=disk error								...OK
	;25= module not connected to AP, the user has to set his module externally.OK

;ftp	;4= check_module_answer routine did not found the answer from DE	...OK
	;5= uploaded data not sent correctly (ftp_upl_send)			...OK
	;6= cipsend_lod routine error. Module not ready to send data for upload	...OK
	;10= error in connecting to ftp server (ftp_login)(probably wrong URL)	...OK
	;11= error in receiving ftp answer (receive_ftp_answer)			...OK
	;12= "+IPD," string not found in the incoming bytes (look_for_ipd)	...OK
	;13= FTP server did not confirm answer 225 on download attempt (ftp_download_file, or retrieve directory...OK
	;16= ABOR command not successful					...OK
	;17= upload: connection not accepted (code 150 not received)		...OK
	;18= upload: transfer not ok (code 226 not accepted)			...OK
	;19= initial check. Connected to server, not good answer to NOOP cmnd	...OK
	;20= ABOR command initiated by the user					...OK
	;21= download: files does not exist					...OK
	;22= file does not exist on ftp server					...OK
	;23= download: block of data receive error				...OK
	;24= server did not respond with "226 Transfer OK"			...OK
	;25= command sent ok, but return code other than expected		...OK
	;26= no data available in passive receive mode (routine 84)		...OK
	;27= command for create dir not accepted (create dir)
	;28=speed management: AT command not accepted						... present in the code but not used
	;29=speed management: all speeds tested, timeout, fix it in terminal-add it in the next ver... present in the code but not used
	;30=speed management: failed, probably Wifi module wrongly set,fix in terminal-add it in the next ver... present in the code but not used
	;31=user defined speed_ AT+UART_CUR command not sent			...???
	;32=user defined routine_ speed in UART not set				...???
	;33=user defined speed_ you try to set nonsence speed (ie. > 23)	...???
	;34= dir retrieve error
	;35= (look_for_ipd) 2nd error


BUGS
****
If you encounter bugs during directory reading, press R to reread directory. If you get stuck, press reset and start again. Bugs do not make any harm, they are just like any other bugs, make your life a bit harder. I continuusly work to kill'em all:)



ACKNOWLEDGEMENTS
****************
Primarily: Busy for his couple of handful routines and advices, his idea of directory items conception, advices about find function
LMN, Lanex, SCJoe- for inspiration and knowledge


